Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
Mac and OpenDoc are trademarks of Apple Computer, Inc.
Standard Part Kinds
This document defines a standard part kind, frame list, and two annotation kinds, link, and link source list, that many parts should support. These standards are not prescribed by OpenDoc, but their use smooths data interchange between parts supporting different content categories that otherwise do not share a common data format.
This document also discusses file types that text part editors should support.
Frame List
All parts that support embedding should also support a simple part kind for exchanging embedded frames. This part kind can be used to represent embedded frames, without containing part-specific content. By excluding intrinsic content, this type can be supported by any editor that allows embedding, no matter their category. It allows, for example, multiple embedded frames to be dragged from a text part into a part of a different category, without creating an embedded text part at the destination. (Note that when a single embedded frame is dragged, the embedded frame itself is dragged and thus can be directly embedded in a destination part of any category; see the OpenDoc Programmer’s Guide for how to transfer a single embedded frame.)
Frame list is defined for the Mac OS platform only, with the Mac’s native coordinate system implicit in all coordinates in a frame list value. On other platforms, a frame list can be translated into an equivalent value in that platform's native coordinate system by applying a bias transform to convert between the two coordinate spaces.
The user-visible name of this kind in English should be "Frame List".
Category
Do not define a category for the frame list kind.
MacOS File Type
The MacOS file type for this kind is 'frls'.
Finder Icon
Do not define an icon for the file type 'frls' in your part’s 'BNDL' resource. A future release of OpenDoc will define one.
Definition
A C-like definition is used only for documentation purposes. There is actually no such type in OpenDoc.
All geometry is in the coordinate space defined by the transform.
All numbers are in standard (little) endian format.
struct FrameInfo {
ODRect boundingBox;
ODStorageUnitRef frameRef;
};
struct FrameList {
ODTransform transform;
ODPoint extent; // top-left is (0,0)
ODULong numFrames;
FrameInfo frames[numFrames];
};
Example
Assuming that the following two embedded frames (in bold) are selected:
The persistent data will look like this:
transform is the externalized form of the transformation of the normalized bounding box enclosing all frames. Typically, this is just an offset transformation.
extent is the point defining the bottom right of the bounding box enclosing all frames in the list.
frameRef is a reference to a frame’s storage unit.
Usage
This part kind should be written in addition to the current part kind when the user selects embedded frames in your part and cuts, copies, or starts a drag.
If the user pastes or drops content into your part, and you decide to read this kind instead of a higher-fidelity kind, your editor should directly embed the frames. If your part displays the Paste As dialog, and the user chooses this kind, your part should directly embed the frames irrespective of the merge/embed setting. Future versions of the Paste As dialog may disable this kind if embedding is not allowed.
Normally, this part kind is used only for data interchange. However, if several embedded frames are dragged to the Finder, a document will be created with this kind as the root kind.
Your part can support this document by supporting the frame list file type. Add this type to your nmap, and in your InitPartFromStorage method, look for this file type. If the user makes any changes to the document that adds intrinsic content to your part, you should change the part kind to your preferred kind, according to the HI Guidelines.
Links and Link Sources associated with a Single Embedded Frame Data Transfer Operation
When externalizing a single embedded frame to a data transfer object (clipboard or drag and drop) using the kODPropContentFrame property, any link or link sources associated with the single emebedded frame by the containing part should be represented in the kODPropProxyContents property.
By representing this data using standard kinds, and in a standard way, it becomes possible for a different part editor, which also supports linking, to establish an appropriate link or link source with relation to the dropped or pasted content. This standard applies only to data transfers of a single embedded frame using the kODPropContentFrame property.
ODStorageUnitRef : strong reference to the cloned link's storage unit
ODLinkInfo : the link info record you mantain for this link destination
ISO String : the contents of the linkInfo.kind field
optional additional link destination related data:
ISO String : signature identifying the format of the additional information
Anything: Additional information about the link destination.
ISO strings are represented as an ODULong value indicating the number of bytes of data, followed by the string data, which includes the required null terminator.
Format of kODLinkSourceList value:
one or more repetitions of:
ODStorageUnitRef : strong reference to the cloned link source's storage unit
ODUpdateID : update ID associated with the current content
Usage
When externalizing a selection consisting of a single embedded frame, and one or more link sources each of which contains exactly that content, add the kODPropProxyContents property to the data transfer storage unit, and add to that property a value of type kODLinkSourceList as defined above. (Following the linking recipes, and the HI guidelines, it's unusual to have more than one link source associated with the same content, but it is unfortunately occasionally unavoidable.)
For each link source, follow the linking recipes to obtain a strong storage unit ref from the ID derived when cloning it to the data transfer draft (the 'to draft' in the recipes), and write it out to the kODLinkSourceList value. Then write out a value of type ODUpdateID representing the internal update ID of the transfered content. If the link is manual, this is not necessarily the same as the one which would be returned by ODLinkSource::GetUpdateID().
When externalizing a selection consisting of a single embedded frame, and a link destination which contains exactly that content, add the kODPropProxyContents property to the data transfer storage unit, and add to that property a value of type kODLink as defined above. (There is no way that more than one link destination can be associated with the same content. There can occasionally be both a single link destination and one or more link sources associated with the same content).
Follow the linking recipes to obtain a strong storage unit ref from the ID derived when cloning the link to the data transfer draft (the 'to draft' in the recipes), and write it out to the kODLink value. Following that write the ODLinkInfo record that you maintain for this destination. Then write out the ISO string for the linkInfo.kind member:
StorageUnitSetISOStrValue(su, ev, linkInfo.kind);
You may optionally follow the required link destination data with additional data related to the link. Begin any such data with a unique signature, such as a content kind string, so that another instance of the same editor can recognize what follows as a format that it understands.
When internalizing content, check for the kODPropProxyContent property, and for each of the standard values.
For value type kODLinkSourceList, use the ODStorageUnit::GetSize() function to determine the extent of the link source references contained in the value thusly:
ODULong size = su->GetSize(ev);
while (size >= sizeof(ODStorageUnitRef) + sizeof(ODUpdateID))
Validate and internalize a link destination from the storage unit reference in accordance with the linking recipes, and associate it with the embedded frame in accordance with your part's content model.
The routines StorageUnitSetISOStrValue and StorageUnitGetISOStrValue are not provided in OpenDoc or the OpenDoc Utilities. They're referenced above for demonstration purposes only. Implementations of these routines can be found in the sample code source file "LinkingPartUtils.cpp".
Macintosh Text Parts
Part editors supporting the plain text or styled text categories should support some basic Macintosh file types for text. This allows users to drag these non-OpenDoc files from the Finder into an OpenDoc document, and have the file contents merged into a text part or embedded as a new part. As documented in the OpenDoc Programmer’s Guide, OpenDoc does not automatically read data from a non-OpenDoc file. Instead, parts read data from the file when performing a paste, receiving a drop, or when initializing from a storage unit containing a file type kind.
Developers for the Macintosh should note that there are four standard file types for text in common use:
'TEXT' -- ASCII characters in the data fork, 'styl' resource containing style information in the resource fork.
'sEXT' -- Same format as 'TEXT', but a stationeryfile created by SimpleText or TeachText.
'ttro' -- Same format as 'TEXT', but treated as read-only by SimpleText and TeachText.
'clpt' -- A text clippings file; no data fork, 'TEXT' and 'styl' resources in the resource fork.
In addition, there are other text file types used by applications that your part could also support.
